<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Using dbstl in multithreaded applications</title>
    <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
    <link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" />
    <link rel="up" href="stl.html" title="Chapter 7. Standard Template Library API" />
    <link rel="prev" href="stl_txn_usage.html" title="Using transactions in dbstl" />
    <link rel="next" href="stl_primitive_rw.html" title="Working with primitive types" />
  </head>
  <body>
    <div xmlns="" class="navheader">
      <div class="libver">
        <p>Library Version 11.2.5.3</p>
      </div>
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">Using dbstl in multithreaded applications</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="stl_txn_usage.html">Prev</a> </td>
          <th width="60%" align="center">Chapter 7. Standard Template Library API</th>
          <td width="20%" align="right"> <a accesskey="n" href="stl_primitive_rw.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="sect1" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both"><a id="stl_mt_usage"></a>Using dbstl in multithreaded applications</h2>
          </div>
        </div>
      </div>
      <p>
    Multithreaded use of dbstl must obey the following guidelines:
</p>
      <div class="orderedlist">
        <ol type="1">
          <li>
            <p>
    For a few non-standard platforms, you must first configure dbstl for that
    platform, but usually the configure script will
    detect the applicable thread local storage (TLS) modifier to use, and
    then use it. If no appropriate TLS is found, the pthread TLS API is used.
</p>
          </li>
          <li>
            <p>
    Perform all initializations in a single thread.
    <code class="methodname">dbstl::dbstl_startup()</code> should be called
    mutually exclusive in a single thread before using dbstl. If dbstl is
    used in only a single thread, this function does not need to be called.
</p>
            <p>
    If necessary, callback functions for a complex type T must be 
    registered to the singleton of
    DbstlElemTraits&lt;T&gt; before any container related to T (for
    example, <code class="literal">db_vector&lt;T&gt;</code>), is used, and certain
    isolation may be required among multiple threads. The best way to do
    this is to register all callback function pointers into the singleton
    in a single thread before making use of the containers.
</p>
            <p>
    All container cursor open flags and auto commit transaction
    begin/commit flags must be set in a single thread before storing
    objects into or reading objects from the container.
</p>
          </li>
          <li>
            <p>
    Environment and database handles can optionally be shared across
    threads.  If handles are shared, they must be registered in each thread
    that is using the handle (either directly, or indirectly using the
    containers that own the handles). You do this using the
    <code class="function">dbstl::register_db()</code> and
    <code class="function">dbstl::register_db_env()</code> functions. Note that
    these functions are not necessary if the current thread called
    <code class="function">dbstl::open_db()</code> or
    <code class="function">dbstl::open_env()</code> for the handle that is being
    shared. This is because the open functions automatically register the
    handle for you.
</p>
            <p>
    Note that the get/set functions that provide access to container data
    members are not mutex-protected because these data members are supposed
    to be set only once at container object initialization. Applications
    wishing to modify them after initialization must supply their own
    protection.
</p>
          </li>
          <li>
            <p>
    While container objects can be shared between multiple threads,
    iterators and transactions can not be shared.
</p>
          </li>
          <li>
            <p>
    Set the <span class="bold"><strong>directdb_get</strong></span> parameter of the
    container <code class="methodname">begin()</code> method to
    <code class="literal">true</code> in order to guarantee that referenced key/data
    pairs are always obtained from the database and not from an iterator's
    cached value.  (This is the default behavior.) You should do this
    because otherwise a rare situation may occur.  Given db_vector_iterator
    i1 and i2 used in the same iteration, setting *i1 = new_value will not
    update i2, and *i2 will return the original value.
</p>
          </li>
          <li>
            <p>
    If using a CDS database, only const iterators or read-only non-const
    iterators should be used for read only iterations. Otherwise, when
    multiple threads try to open read-write iterators at the same time,
    performance is greatly degraded because CDS only supports one write cursor
    open at any moment.  The use of read-only iterators is good practice
    in general because dbstl contains internal optimizations for read-only
    iterators.
</p>
            <p>
    To create a read-only iterator, do one of the following:
</p>
            <div class="itemizedlist">
              <ul type="disc">
                <li>
                  <p>
                Use a <code class="literal">const</code> reference to the container
                object, then call the container's
                <code class="methodname">begin()</code> method using the const
                reference, and then store the return value from the 
                <code class="methodname">begin()</code> method in a
                <code class="methodname">db_vector::const_iterator</code>.
            </p>
                </li>
                <li>
                  <p>
                If you are using a non-const container object, then simply
                pass <code class="literal">true</code> to the 
                <span class="bold"><strong>readonly</strong></span> parameter of the
                non-const <code class="methodname">begin()</code> method.
            </p>
                </li>
              </ul>
            </div>
          </li>
          <li>
            <p>  
    When using DS, CDS or TDS, enable the locking subsystem by passing the
    <a href="../api_reference/C/envopen.html#envopen_DB_INIT_LOCK" class="olink">DB_INIT_LOCK</a> flag to <code class="methodname">DbEnv::open()</code>.
</p>
          </li>
          <li>
            <p>  
    Perform portable thread synchronization within a process by calling the
    following functions. These are all global functions in the "dbstl" name
    space:
</p>
            <table class="simplelist" border="0" summary="Simple list">
              <tr>
                <td>
                  <code class="function">db_mutex_t alloc_mutex();</code>
                </td>
              </tr>
              <tr>
                <td>
                  <code class="function">int lock_mutex(db_mutex_t);</code>
                </td>
              </tr>
              <tr>
                <td>
                  <code class="function">int unlock_mutex(db_mutex_t);</code>
                </td>
              </tr>
              <tr>
                <td>
                  <code class="function">void free_mutex(db_mutex_t);</code>
                </td>
              </tr>
            </table>
            <p>
    These functions use an internal dbstl environment's mutex functionality
    to synchronize. As a result, the synchronization is portable across all
    platforms supported by Berkeley DB.
</p>
          </li>
        </ol>
      </div>
      <p>  
    The <code class="classname">WorkerThread</code> class provides example code
    demonstrating the use of dbstl in multi-threaded applications. You can
    find this class implemented in the dbstl test suite.
</p>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="stl_txn_usage.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="stl.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="stl_primitive_rw.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">Using transactions in dbstl </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> Working with primitive types </td>
        </tr>
      </table>
    </div>
  </body>
</html>
